HAL LPTIM migration: List of applicable concepts ¶

This section provides information about the HAL LPTIM applicable architecture concepts.

Concepts for LPTIM ¶

Concept	Description
Separation of initialization and configuration functions	The initialization and the configuration are split into 2 level functions: `HAL_LPTIM_Init`: initializes the handle and links it to an LPTIM instance. `HAL_LPTIM_SetConfig`: configures the common LPTIM settings (prescaler, counter mode,…).
Removal and conversion of init structure to configuration structure	The initialization structure has been removed and converted into `HAL_LPTIM_SetConfig` function.
Renaming of the handle structure	The handle structure has been renamed to `hal_lptim_handle_t`
Renaming unitary init structures	The structure `LPTIM_InitTypeDef` is no longer available and has been replaced by `hal_lptim_config_t`
Remove MspInit and MspDeInit callbacks	`HAL_LPTIM_MspInit` and `HAL_LPTIM_MspDeInit` are no longer available and have been replaced by a user sequence to initialize and configure the LPTIM .
Unitary configuration APIs	New APIs are available to set and get LPTIM features.
Dedicated DMA link APIs replace generic __HAL_LINKDMA macro	The `__HAL_LINKDMA` macro is no longer provided and new functions `HAL_LPTIM_SetDMA` is provided to link the LPTIM handle to a DMA handle.
Introduction of HAL user data set/get APIs	Two functions to set and get user data are available: `HAL_LPTIM_SetUserData` and `HAL_LPTIM_GetUserData`.
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each LPTIM event. These functions are used to register callback functions for different LPTIM events.
Introduce specialized IRQ handlers	Global `HAL_LPTIM_IRQHandler` still available. In addition, new process-specific handlers `HAL_LPTIM_IRQHandler_<PROCESS>` are provided for handling individual processes separately. `HAL_LPTIM_TRGI_DIR_IRQHandler` `HAL_LPTIM_CC_IRQHandler` `HAL_LPTIM_UPD_IRQHandler`
HAL implementation with LL inline functions	HAL LPTIM APIs now rely on LL APIs rather than performing direct register access.
Define statements and enumerations redirected to LL equivalents	HAL LPTIM define statements and enumerations are based on LL define statements.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL LPTIM driver, and equivalent services are ensured through the LL APIs.
Revised and optimized HAL state machine	The LPTIM now is managed by two state machine : Global state machine Channel state machine : State for the output channel. State for the input channel.
Revised and optimized HAL API status returns	The HAL LPTIM functions were updated to return: `HAL_INVALID_PARAM`: in case of a NULL p_config structure pointer. `HAL_ERROR`: in case of an error. `HAL_TIMEOUT`: in case of a user timeout. `HAL_BUSY`: in case of an ongoing process. `HAL_OK`: in case of a successfully completed operation.
Revised and optimized HAL error management	The HAL error handling mechanisms have been redesigned to improve the detection, reporting, and handling of errors.
New APIs for filtering optional asynchronous process interrupts	New APIs are provided in the LPTIM to filter and manage asynchronous process interrupts : `HAL_LPTIM_Start_DMA_Opt` `HAL_LPTIM_IC_StartChannel_DMA_Opt`
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL LPTIM driver have been removed and replaced by `_t`.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The parameters and state are checked using `ASSERT_DBG_STATE` and `ASSERT_DBG_PARAM` macros.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL LPTIM header file remains and all macros, define statements, and functions from `hal_lptim_ex.h` have been moved to `hal_lptim.h`.
Add HAL PPP Services for Drivers with Handle to Retrieve Corresponding Peripheral Clock Frequency.	HAL LPTIM provides new API to retrieve clock frequency `HAL_LPTIM_GetClockFreq`.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including LPTIM instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Change Channel Argument to 0-Based Enumeration in Timer Channels	The HAL channels are now represented as an incremental 0-based enumeration.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL LPTIM functions start with `HAL_LPTIM`. All HAL LPTIM enumerations and structures start with `hal_lptim`.

Other HAL LPTIM changes ¶

Concept	Consideration
LPTIM clock source:	In HAL1: The initialization structure, `LPTIM_InitTypeDef`, allows selection between two clock sources: `LPTIM_CLOCKSOURCE_APBCLOCK_LPOSC` (main/internal clock) `LPTIM_CLOCKSOURCE_ULPTIM` (ultra-low-power clock) Other fields in the configuration structure, like `Input1Source` and `Input2Source`, are included for advanced features (like external clock or encoder modes), but can usually be ignored for basic use. In HAL2: The clock configuration has been made more flexible. The following options can now be selected: Internal clock External clock (synchronous or asynchronous) Encoder mode (with different polarity/submodes) The configuration is done with a single enumeration ( `hal_lptim_clk_src_t`), making it clear which clock and mode you are using. Note The APIs `HAL_LPTIM_Encoder_xxx` disappear since, once the clock source is selected as encoder, the timer is started/stopped with the usual APIs `HAL_LPTIM_Start[_IT, _DMA]` and `HAL_LPTIM_Stop[_IT, _DMA]`.
Input Capture mode:	In HAL1: To start or stop Input Capture in Polling, Interrupt (IT), or DMA mode, specific APIs are provided for each mode: Polling mode: `HAL_LPTIM_IC_Start()` / `HAL_LPTIM_IC_Stop()` Interrupt mode: `HAL_LPTIM_IC_Start_IT()` / `HAL_LPTIM_IC_Stop_IT()` DMA mode: `HAL_LPTIM_IC_Start_DMA()` / `HAL_LPTIM_IC_Stop_DMA()` These APIs internally handle starting and stopping the LPTIM counter, so no separate call to start or stop the timer is needed In HAL2: Starting and stopping Input Capture is done using dedicated channel APIs for each mode(Polling, IT and DMA): Polling mode: `HAL_LPTIM_IC_StartChannel()` / `HAL_LPTIM_IC_StopChannel()` Interrupt mode: `HAL_LPTIM_IC_StartChannel_IT()` / `HAL_LPTIM_IC_StopChannel_IT()` DMA mode: `HAL_LPTIM_IC_StartChannel_DMA()` / `HAL_LPTIM_IC_StopChannel_DMA()` In contrast to HAL1, these APIs do not start or stop the LPTIM timer itself. The user must explicitly start and stop the timer by calling: `HAL_LPTIM_Start()` to start the timer, and `HAL_LPTIM_Stop()` to stop it.
LPTIM Counter output modes:	In HAL1: Different APIs are provided for each output type (PWM, One-Pulse, SetOnce) and for Timeout functionality. The output waveform and timeout behavior depend on which API is used to start the counter. In HAL2: The separate APIs for each output type ( `HAL_LPTIM_PWM_Start/Stop`, `HAL_LPTIM_OnePulse_Start/Stop`, `HAL_LPTIM_SetOnce_Start/Stop`) have been removed. Instead, the desired mode is first selected using `HAL_LPTIM_SetConfig()`, then the channel is configured as an output by calling `HAL_LPTIM_OC_SetConfigChannel()`, and the channel is started with `HAL_LPTIM_OC_StartChannel()`. Once the channel is configured and started, the LPTIM is started using `HAL_LPTIM_Start()`, similarly to the HAL TIM driver.

Concept

Consideration

LPTIM clock source:

In HAL1: The initialization structure, LPTIM_InitTypeDef, allows selection between two clock sources:

LPTIM_CLOCKSOURCE_APBCLOCK_LPOSC (main/internal clock)
LPTIM_CLOCKSOURCE_ULPTIM (ultra-low-power clock)

Other fields in the configuration structure, like Input1Source and Input2Source, are included for advanced features (like external clock or encoder modes), but can usually be ignored for basic use.

In HAL2: The clock configuration has been made more flexible. The following options can now be selected:

Internal clock
External clock (synchronous or asynchronous)
Encoder mode (with different polarity/submodes)

The configuration is done with a single enumeration ( hal_lptim_clk_src_t), making it clear which clock and mode you are using.

Note

The APIs HAL_LPTIM_Encoder_xxx disappear since, once the clock source is selected as encoder, the timer is started/stopped with the usual APIs HAL_LPTIM_Start[_IT, _DMA] and HAL_LPTIM_Stop[_IT, _DMA].

Input Capture mode:

In HAL1: To start or stop Input Capture in Polling, Interrupt (IT), or DMA mode, specific APIs are provided for each mode:

Polling mode: HAL_LPTIM_IC_Start() / HAL_LPTIM_IC_Stop()
Interrupt mode: HAL_LPTIM_IC_Start_IT() / HAL_LPTIM_IC_Stop_IT()
DMA mode: HAL_LPTIM_IC_Start_DMA() / HAL_LPTIM_IC_Stop_DMA()

These APIs internally handle starting and stopping the LPTIM counter, so no separate call to start or stop the timer is needed

In HAL2: Starting and stopping Input Capture is done using dedicated channel APIs for each mode(Polling, IT and DMA):

Polling mode: HAL_LPTIM_IC_StartChannel() / HAL_LPTIM_IC_StopChannel()
Interrupt mode: HAL_LPTIM_IC_StartChannel_IT() / HAL_LPTIM_IC_StopChannel_IT()
DMA mode: HAL_LPTIM_IC_StartChannel_DMA() / HAL_LPTIM_IC_StopChannel_DMA()

In contrast to HAL1, these APIs do not start or stop the LPTIM timer itself. The user must explicitly start and stop the timer by calling: HAL_LPTIM_Start() to start the timer, and HAL_LPTIM_Stop() to stop it.

LPTIM Counter output modes:

In HAL1: Different APIs are provided for each output type (PWM, One-Pulse, SetOnce) and for Timeout functionality. The output waveform and timeout behavior depend on which API is used to start the counter.

In HAL2: The separate APIs for each output type ( HAL_LPTIM_PWM_Start/Stop, HAL_LPTIM_OnePulse_Start/Stop, HAL_LPTIM_SetOnce_Start/Stop) have been removed.

Instead, the desired mode is first selected using HAL_LPTIM_SetConfig(), then the channel is configured as an output by calling HAL_LPTIM_OC_SetConfigChannel(), and the channel is started with HAL_LPTIM_OC_StartChannel(). Once the channel is configured and started, the LPTIM is started using HAL_LPTIM_Start(), similarly to the HAL TIM driver.